【工具】Swagger2写接口注释

时间：2022-07-15 01:53:57

一、遇到的问题

作为一名coder，经常需要向别人提供接口，或者调用别人的接口。于是就有了接口参数是什么意思，要怎么传参数，返回值是什么意思……有多少调用方，就会有多少人来询问这些参数。如果是长时间之后，自己或许都不知道这些参数是什么意思。于是维护接口文档便成了一项必不可少的工作，维护文档也有很多问题：

  • 如果手工写会很费劲
  • 接口变更后可能会忘了同步文档
  • ……

二、Swagger配置

Swagger（官方文档）可以快速帮助实现接口api的维护与简单测试。

a、引入maven依赖包

    <dependency>

      <groupId>io.springfox</groupId>

      <artifactId>springfox-swagger2</artifactId>

      <version>2.5.0</version>

    </dependency>

    <dependency>

      <groupId>io.springfox</groupId>

      <artifactId>springfox-swagger-ui</artifactId>

      <version>2.5.0</version>

    </dependency>

b、配置Swagger

@Configuration

@EnableSwagger2
@Profile("dev")

public class SwaggerConfig {

    public static final String SWAGGER_SCAN_BASE_PACKAGE = "api.doc.demo.controller";

    public static final String VERSION = "1.0.0";

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .select()

                /**api接口包扫描路径*/

                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))

                /**可以根据url路径设置哪些请求加入文档，忽略哪些请求*/

                .paths(PathSelectors.any())

                .build();

    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

                /**设置文档的标题*/

                .title("Swagger2 接口文档示例")

                /**设置文档的描述*/

                .description("更多内容请关注：http://www.abc.com")

                /**设置文档的联系方式*/

                .contact(new Contact("create by XXX", "http://www.abc.com", "xxxx.@xxx.com"))

                /**设置文档的License信息->1.3 License information*/

                .termsOfServiceUrl("www.abc.com")

                .license("xxx")

                .licenseUrl("http://www.xxx.com")

                /**设置文档的版本信息-> 1.1 Version information*/

                .version(VERSION)

                .build();

    }

}

c、常用注解

  • @ApiOperation ： api说明
    @ApiOperation(value="获取用户列表", notes="获取所有用户列表",produces = "application/json")

    @RequestMapping(value="/getList", method= RequestMethod.GET)

    public List<UserModel> getUserList() {

        return getDemoList();

    }

【工具】Swagger2写接口注释

  • @ApiResponses ：默认Response的基础上增加新的Response说明
  • @ApiImplicitParam ： 描述接口参数
@ApiImplicitParam(name = "userId",value = "用户ID",dataType = "int",paramType = "path")
  • @ApiImplicitParams ： 多个参数
@ApiImplicitParams({
        @ApiImplicitParam(name = "id",value = "用户ID",paramType = "path",dataType = "int"),
        @ApiImplicitParam(name = "userName",value = "用户名称",paramType = "form",dataType = "string")
})
  • @ApiModel : model属性
@ApiModel(value = "user", description = "user对象")
public class UserModel {
    @ApiModelProperty(value = "ID", dataType = "Integer", required = true)
    private Integer userId;
    @ApiModelProperty(value = "用戶名", dataType = "String")
    private String userName;
    @ApiModelProperty(value = "性別", dataType = "Integer", allowableValues = "0,1,2")
    private Integer sex;
}

这样就可以通过访问 http://localhost:8080/swagger-ui.html 看到接口API调用说明。demo

相关文章