随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。
前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。




创建一个Spring boot工程:


加入Swagger依赖:
       <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger2</artifactId>            <version>2.7.0</version>        </dependency>        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger-ui</artifactId>            <version>2.7.0</version>        </dependency>
写一个controller作为API接口:
@RestController@RequestMapping("/demo")public class DemoController {    @RequestMapping(value = "/add", method = RequestMethod.POST)    public User addUser(@RequestBody @Valid User user){        user.setDescription("had been dealed");        return user;    }    @RequestMapping(value="/delete/{id}", method = RequestMethod.DELETE)    public ResponseEntity delete(@PathVariable Integer id){        //mock deleted;        return new ResponseEntity("User had been deleted", HttpStatus.OK);    }    @RequestMapping(value = "/show", method= RequestMethod.GET)    public User showUser(@RequestParam("id") Integer id){        User user = new User();        user.setId(1);        user.setDescription("show user");        user.setAge(100);        user.setUsername("test");        return user;    }}
配置Swagger：
@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket productApi() {        return new Docket(DocumentationType.SWAGGER_2)                .select()                //指定要生成api文档的根包                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))                //路径配置                .paths(regex("/demo.*"))                .build()                .apiInfo(apiInfo());    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("Swagger2的Restful API 文档")                .description("Spring Boot和Swagger的结合")                .version("1.0")                .build();    }}
配置好后，就可以启动你的spring boot 应用，先一睹swagger的芳容，进入这个地址:http://localhost:8000/swagger-ui.html,具体的服务器端口号撒的根据你本地的进行更改，然后就会看到这个页面:

但是，虽然能看到文档页面了，但这还比较简陋，各个Restful方法的具体文档都还没有，这些还得靠我们去代码里加入，毕竟还不是那么智能的，怎么加入呢，请接着往下看。
用@Api在Controller类上定义这个服务的描述信息，像这样:
@RestController@RequestMapping("/demo")@Api(value="demo", description="这是一个Swagger demo的服务")public class DemoController {    .....}
然后在swagger ui里面就看到了对这个controller的描述信息：

有注解能对controller进行描述，当然也有注解能对里面的各个方法进行描述，这就是@ApiOperation和它的小伙伴们:
@RequestMapping(value = "/add", method = RequestMethod.POST,produces = "application/json")    @ApiOperation(value = "新增一个用户", response = User.class)    @ApiResponses(value = {            @ApiResponse(code = 200, message = "成功保存"),            @ApiResponse(code = 401, message = "你没权限"),            @ApiResponse(code = 403, message = "你被禁止访问了"),            @ApiResponse(code = 404, message = "没找到，哈哈哈")    }    )    @ApiImplicitParam(name = "user",            value = "要新增的用户",            dataType = "User",//This can be the class name or a primitive            required = true,            paramType = "body")    public User addUser(@RequestBody @Valid User user){        user.setDescription("had been dealed");        return user;    }    @RequestMapping(value="/delete/{id}", method = RequestMethod.DELETE,produces = "application/json")    @ApiOperation(value = "删除一个用户", response = ResponseEntity.class)    @ApiResponses(value = {            @ApiResponse(code = 200, message = "成功保存"),            @ApiResponse(code = 401, message = "你没权限"),            @ApiResponse(code = 403, message = "你被禁止访问了"),            @ApiResponse(code = 404, message = "没找到，哈哈哈")    }    )    @ApiImplicitParam(name="id",            value = "要删除的用户id",            dataType = "int",//This can be the class name or a primitive            required = true,            paramType = "path")//Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}    public ResponseEntity delete(@PathVariable Integer id){        //mock deleted;        return new ResponseEntity("User had been deleted", HttpStatus.OK);    }    @RequestMapping(value = "/show", method= RequestMethod.GET,produces = "application/json")    @ApiOperation(value = "显示一个用户", response = ResponseEntity.class)    @ApiResponses(value = {            @ApiResponse(code = 200, message = "成功保存"),            @ApiResponse(code = 401, message = "你没权限"),            @ApiResponse(code = 403, message = "你被禁止访问了"),            @ApiResponse(code = 404, message = "没找到，哈哈哈")    }    )    @ApiImplicitParams({            @ApiImplicitParam(name="id",                    value = "要删除的用户id",                    dataType = "int",//This can be the class name or a primitive                    required = true,                    paramType = "query"),//Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}            @ApiImplicitParam(name = "param",                    value = "其他参数",                    dataType = "String",//This can be the class name or a primitive                    required = true,                    paramType = "query")//Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}    })    public User showUser(@RequestParam("id") Integer id,@RequestParam("param") String otherParam){        User user = new User();        user.setId(1);        user.setDescription("show user");        user.setAge(100);        user.setUsername("test");        return user;    }
当参数是复杂类型(非原始类或及其包装类)时,就需要用到@ApiModel和@ApiModelProperty：
@Data@ApiModelpublic class User {    @ApiModelProperty(notes = "用户id",required = false,dataType="Integer")    private Integer id;    @NotBlank    @ApiModelProperty(notes = "用户名",required = true,dataType="String")    private String username;    @NotNull    @Max(100)    @Min(1)    @ApiModelProperty(notes = "年龄",required = true,dataType="Integer",allowableValues = "range[0,100]")    private Integer age;    @ApiModelProperty(notes = "描述",required = false,dataType="String")    private String description;}
注解说明:
@ApiOperation：对方法进行描述，说明方法作用
@ApiResponses：表示一组响应
@ApiImplicitParams：对方法的多个参数进行描述
@ApiImplicitParam：对单个的参数进行描述(name:参数名,value:参数的描述,dataType:参数类型,required:是否必须,paramType:参数来源方式)
@ApiModel：对复杂类型参数进行说明
@ApiModelProperty：对复杂类型字段进行说明
让我们看看最终的效果图吧:


这就是最终出来的文档页面，那个Try it out!按钮是用来进行接口测试的，你可以填入参数进行测试。




链接：https://www.jianshu.com/p/0e498041f882
来源：简书

       随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。
前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。




创建一个Spring boot工程:


加入Swagger依赖:
       <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger2</artifactId>            <version>2.7.0</version>        </dependency>        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger-ui</artifactId>            <version>2.7.0</version>        </dependency>
写一个controller作为API接口:
@RestController@RequestMapping("/demo")public class DemoController {    @RequestMapping(value = "/add", method = RequestMethod.POST)    public User addUser(@RequestBody @Valid User user){        user.setDescription("had been dealed");        return user;    }    @RequestMapping(value="/delete/{id}", method = RequestMethod.DELETE)    public ResponseEntity delete(@PathVariable Integer id){        //mock deleted;        return new ResponseEntity("User had been deleted", HttpStatus.OK);    }    @RequestMapping(value = "/show", method= RequestMethod.GET)    public User showUser(@RequestParam("id") Integer id){        User user = new User();        user.setId(1);        user.setDescription("show user");        user.setAge(100);        user.setUsername("test");        return user;    }}
配置Swagger：
@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket productApi() {        return new Docket(DocumentationType.SWAGGER_2)                .select()                //指定要生成api文档的根包                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))                //路径配置                .paths(regex("/demo.*"))                .build()                .apiInfo(apiInfo());    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("Swagger2的Restful API 文档")                .description("Spring Boot和Swagger的结合")                .version("1.0")                .build();    }}
配置好后，就可以启动你的spring boot 应用，先一睹swagger的芳容，进入这个地址:http://localhost:8000/swagger-ui.html,具体的服务器端口号撒的根据你本地的进行更改，然后就会看到这个页面:

但是，虽然能看到文档页面了，但这还比较简陋，各个Restful方法的具体文档都还没有，这些还得靠我们去代码里加入，毕竟还不是那么智能的，怎么加入呢，请接着往下看。
用@Api在Controller类上定义这个服务的描述信息，像这样:
@RestController@RequestMapping("/demo")@Api(value="demo", description="这是一个Swagger demo的服务")public class DemoController {    .....}
然后在swagger ui里面就看到了对这个controller的描述信息：

有注解能对controller进行描述，当然也有注解能对里面的各个方法进行描述，这就是@ApiOperation和它的小伙伴们:
@RequestMapping(value = "/add", method = RequestMethod.POST,produces = "application/json")    @ApiOperation(value = "新增一个用户", response = User.class)    @ApiResponses(value = {            @ApiResponse(code = 200, message = "成功保存"),            @ApiResponse(code = 401, message = "你没权限"),            @ApiResponse(code = 403, message = "你被禁止访问了"),            @ApiResponse(code = 404, message = "没找到，哈哈哈")    }    )    @ApiImplicitParam(name = "user",            value = "要新增的用户",            dataType = "User",//This can be the class name or a primitive            required = true,            paramType = "body")    public User addUser(@RequestBody @Valid User user){        user.setDescription("had been dealed");        return user;    }    @RequestMapping(value="/delete/{id}", method = RequestMethod.DELETE,produces = "application/json")    @ApiOperation(value = "删除一个用户", response = ResponseEntity.class)    @ApiResponses(value = {            @ApiResponse(code = 200, message = "成功保存"),            @ApiResponse(code = 401, message = "你没权限"),            @ApiResponse(code = 403, message = "你被禁止访问了"),            @ApiResponse(code = 404, message = "没找到，哈哈哈")    }    )    @ApiImplicitParam(name="id",            value = "要删除的用户id",            dataType = "int",//This can be the class name or a primitive            required = true,            paramType = "path")//Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}    public ResponseEntity delete(@PathVariable Integer id){        //mock deleted;        return new ResponseEntity("User had been deleted", HttpStatus.OK);    }    @RequestMapping(value = "/show", method= RequestMethod.GET,produces = "application/json")    @ApiOperation(value = "显示一个用户", response = ResponseEntity.class)    @ApiResponses(value = {            @ApiResponse(code = 200, message = "成功保存"),            @ApiResponse(code = 401, message = "你没权限"),            @ApiResponse(code = 403, message = "你被禁止访问了"),            @ApiResponse(code = 404, message = "没找到，哈哈哈")    }    )    @ApiImplicitParams({            @ApiImplicitParam(name="id",                    value = "要删除的用户id",                    dataType = "int",//This can be the class name or a primitive                    required = true,                    paramType = "query"),//Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}            @ApiImplicitParam(name = "param",                    value = "其他参数",                    dataType = "String",//This can be the class name or a primitive                    required = true,                    paramType = "query")//Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}    })    public User showUser(@RequestParam("id") Integer id,@RequestParam("param") String otherParam){        User user = new User();        user.setId(1);        user.setDescription("show user");        user.setAge(100);        user.setUsername("test");        return user;    }
当参数是复杂类型(非原始类或及其包装类)时,就需要用到@ApiModel和@ApiModelProperty：
@Data@ApiModelpublic class User {    @ApiModelProperty(notes = "用户id",required = false,dataType="Integer")    private Integer id;    @NotBlank    @ApiModelProperty(notes = "用户名",required = true,dataType="String")    private String username;    @NotNull    @Max(100)    @Min(1)    @ApiModelProperty(notes = "年龄",required = true,dataType="Integer",allowableValues = "range[0,100]")    private Integer age;    @ApiModelProperty(notes = "描述",required = false,dataType="String")    private String description;}
注解说明:
@ApiOperation：对方法进行描述，说明方法作用
@ApiResponses：表示一组响应
@ApiImplicitParams：对方法的多个参数进行描述
@ApiImplicitParam：对单个的参数进行描述(name:参数名,value:参数的描述,dataType:参数类型,required:是否必须,paramType:参数来源方式)
@ApiModel：对复杂类型参数进行说明
@ApiModelProperty：对复杂类型字段进行说明
让我们看看最终的效果图吧:


这就是最终出来的文档页面，那个Try it out!按钮是用来进行接口测试的，你可以填入参数进行测试。




链接：https://www.jianshu.com/p/0e498041f882
来源：简书