入门级教程

https://www.cnblogs.com/jtlgb/p/8532433.html

价值

swagger存在的价值：
前后端分离，提升了文档的重要性，否则前端无法开发，必须要有接口文档。传统的文档方式维护起来麻烦，为了省事，把代码注释和文档注释合二为一，并且额外的提供接口测试的功能。

1. swagger侵入代码，可以直接动态生成API文档，是最简洁的一种方式了，不需要额外的维护文档
2. 支持文档的在线即时生成，只需要维护代码里面的swagger注解，不需要维护其它的文档了。动态生成最新的API文档
3. 一箭双雕啊，既有了代码注释 又有了API文档注释，不管是后端开发和前端开发或者业务人员都一目了然
4. 集代码注释 + API文档 + 测试工具（http接口测试）于一体

Springboot配置

也可以通过SwaggerConfig类来指定包路径和是否开启文档功能

api.swagger.title= springboot利用swagger构建api文档
api.swagger.contact= xx # 作者
api.swagger.version= 2.0
api.swagger.basePackage= com.example.demo.ssm.controller
api.swagger.description= 简单优雅的restfun风格，http://blog.csdn.net/saytime

业务场景

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

Demo

• 注释了该方法的作用(根据部门名称和类型获取所有的部门)，接受的请求类型(Get)
• 参数的个数和含义
• 返回值和返回值的属性信息

    @GetMapping("/findByNameAndType")
    @ResponseBody
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "部门名称", required = true, paramType = "query", dataType = "String"),
            @ApiImplicitParam(name = "type", value = "部门类型", required = true, paramType = "query", dataType = "String")
    })
    @ApiOperation(value = "根据部门名称和类型获取所有的部门", httpMethod = "GET")
    @ApiResponses({@ApiResponse(code = 200, message = "处理成功")})
    public List<Dept> findByNameAndType(@RequestParam(value = "name") String name, @RequestParam(value = "type") String type) {
        return deptService.listDepts();
    }
    
@Data
@ApiModel("部门类")
public class Dept {
    @ApiModelProperty("部门ID")
    private Integer id;
    @ApiModelProperty("部门名称")
    private String name;
}

其它

1. 生产环境关闭 swagger功能：

• 通过nginx配置，不开放 swagger访问即可
• 通过继承SwaggerConfig类，配置 enable(false)即可

2. 默认@API接口下面的所有的方法（对外开放请求的方法）都会生成文档，如果想忽略某个方法，可以使用.则不会出现在API文档当中

    @GetMapping("/testUser")
    @ResponseBody
    @ApiIgnore
    public Integer testUser() {
        userService.selectById(1L);
        userService.listUsers();
        return 1;
    }

3. 查看文档的url
   /swagger-ui.html