• 使用Swagger2自动生成API接口文档


    一、为什么使用Swagger2

    当下很多公司都采取前后端分离的开发模式,前端和后端的工作由不同的工程师完成。在这种开发模式下,维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的,相信大家也都知道这种方式很难保证文档的及时性,这种文档久而久之也就会失去其参考意义,反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式,下面我们就来了解一下它的优点:

    1、代码变,文档变。只需要少量的注解,Swagger 就可以根据代码自动生成 API 文档,很好的保证了文档的时效性。

    2、跨语言性,支持 40 多种语言。

    3、Swagger UI 呈现出来的是一份可交互式的 API 文档,我们可以直接在文档页面尝试 API 的调用,省去了准备复杂的调用参数的过程。

    4、还可以将文档规范导入相关的工具(例如 Postman、SoapUI), 这些工具将会为我们自动地创建自动化测试。

    二、配置使用Swagger2

    1、在pom.xml加入swagger2相关依赖

    复制代码
     1 <!--swagger2的依赖-->
     2 <dependency>
     3    <groupId>io.springfox</groupId>
     4    <artifactId>springfox-swagger2</artifactId>
     5    <version>2.9.2</version>
     6 </dependency>
     7 <dependency>
     8    <groupId>io.springfox</groupId>
     9    <artifactId>springfox-swagger-ui</artifactId>
    10    <version>2.9.2</version>
    11 </dependency>
    复制代码

    2、新建Swagger2Config配置类

    复制代码
     1 import io.swagger.annotations.Api;
     2 import org.springframework.context.annotation.Bean;
     3 import org.springframework.context.annotation.Configuration;
     4 import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
     5 import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
     6 import springfox.documentation.builders.ApiInfoBuilder;
     7 import springfox.documentation.builders.PathSelectors;
     8 import springfox.documentation.builders.RequestHandlerSelectors;
     9 import springfox.documentation.service.*;
    10 import springfox.documentation.spi.DocumentationType;
    11 import springfox.documentation.spi.service.contexts.SecurityContext;
    12 import springfox.documentation.spring.web.plugins.Docket;
    13 import springfox.documentation.swagger2.annotations.EnableSwagger2;
    14 
    15 import java.util.ArrayList;
    16 import java.util.List;
    17 
    18 /**
    19  * @author yunqing
    20  * @date 2019/12/17 10:23
    21  */
    22 @Configuration
    23 @EnableSwagger2
    24 public class Swagger2Config extends WebMvcConfigurationSupport {
    25     @Bean
    26     public Docket createRestApi(){
    27         return new Docket(DocumentationType.SWAGGER_2)
    28                 .apiInfo(apiInfo())
    29                 .select()
    30                 //为当前包下controller生成API文档
    31 //                .apis(RequestHandlerSelectors.basePackage("com.troila"))
    32                 //为有@Api注解的Controller生成API文档
    33 //                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
    34                 //为有@ApiOperation注解的方法生成API文档
    35 //                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
    36                 //为任何接口生成API文档
    37                 .apis(RequestHandlerSelectors.any())
    38                 .paths(PathSelectors.any())
    39                 .build();
    40                 //添加登录认证
    41                 /*.securitySchemes(securitySchemes())
    42                 .securityContexts(securityContexts());*/
    43     }
    44 
    45     private ApiInfo apiInfo() {
    46         Contact contact = new Contact("yunqing", "", "yunqing****@gmail.com");
    47         return new ApiInfoBuilder()
    48                 .title("SwaggerUI演示")
    49                 .description("接口文档,描述词省略200字")
    50                 .contact(contact)
    51                 .version("1.0")
    52                 .build();
    53     }
    54 
    55     /**
    56      * 配置swagger2的静态资源路径
    57      * @param registry
    58      */
    59     @Override
    60     protected void addResourceHandlers(ResourceHandlerRegistry registry) {
    61         // 解决静态资源无法访问
    62         registry.addResourceHandler("/**")
    63                 .addResourceLocations("classpath:/static/");
    64         // 解决swagger无法访问
    65         registry.addResourceHandler("/swagger-ui.html")
    66                 .addResourceLocations("classpath:/META-INF/resources/");
    67         // 解决swagger的js文件无法访问
    68         registry.addResourceHandler("/webjars/**")
    69                 .addResourceLocations("classpath:/META-INF/resources/webjars/");
    70     }
    71 
    72 
    73     /**
    74      * 给API文档接口添加安全认证
    75      */
    76     /*private List<ApiKey> securitySchemes() {
    77         List<ApiKey> apiKeys = new ArrayList<>();
    78         apiKeys.add(new ApiKey("Authorization", "Authorization", "header"));
    79         return apiKeys;
    80     }
    81 
    82     private List<SecurityContext> securityContexts() {
    83         List<SecurityContext> securityContexts = new ArrayList<>();
    84         securityContexts.add(SecurityContext.builder()
    85                 .securityReferences(defaultAuth())
    86                 .forPaths(PathSelectors.regex("^(?!auth).*$")).build());
    87         return securityContexts;
    88     }
    89 
    90     private List<SecurityReference> defaultAuth() {
    91         AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
    92         AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    93         authorizationScopes[0] = authorizationScope;
    94         List<SecurityReference> securityReferences = new ArrayList<>();
    95         securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
    96         return securityReferences;
    97     }*/
    98 }
    复制代码

    3、在shiro配置类中放行swagger2相关资源

    1 //swagger2免拦截
    2 filterChainDefinitionMap.put("/swagger-ui.html**", "anon");
    3 filterChainDefinitionMap.put("/v2/api-docs", "anon");
    4 filterChainDefinitionMap.put("/swagger-resources/**", "anon");
    5 filterChainDefinitionMap.put("/webjars/**", "anon");

    4、配置为哪部分接口生成API文档

    主要是在Swagger2Config配置类中进行createRestApi()方法中进行配置,下面提供四种配置:

    ①为任何接口生成API文档,这种方式不必在接口方法上加任何注解,方便的同时也会因为没有添加任何注解所以生成的API文档也没有注释,可读性不高。

    复制代码
     1 @Bean
     2     public Docket createRestApi(){
     3         return new Docket(DocumentationType.SWAGGER_2)
     4                 .apiInfo(apiInfo())
     5                 .select()
     6                 //为任何接口生成API文档
     7                 .apis(RequestHandlerSelectors.any())
     8                 .paths(PathSelectors.any())
     9                 .build();
    10     }
    复制代码

    ②为当前配置的包下controller生成API文档

    .apis(RequestHandlerSelectors.basePackage("com.troila"))

    ③为有@Api注解的Controller生成API文档

    .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))

    ④为有@ApiOperation注解的方法生成API文档

    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

    三、Swagger2注解详解

    1、@Api :请求类的说明

    @Api:放在请求的类上,与 @Controller 并列,说明类的作用,如用户模块,订单类等。
        tags="说明该类的作用"
        value="该参数没什么意义,所以不需要配置"

    举例:

    复制代码
    1 @Api(tags = "账户相关模块")
    2 @RestController
    3 @RequestMapping("/api/account")
    4 public class AccountController {
    5     //TODO
    6 }
    复制代码

    2、@ApiOperation:方法的说明

    @ApiOperation:"用在请求的方法上,说明方法的作用"
        value="说明方法的作用"
        notes="方法的备注说明"

    举例:

    复制代码
    1 @ApiOperation(value = "修改密码", notes = "方法的备注说明,如果有可以写在这里")
    2 @PostMapping("/changepass")
    3 public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
    4         @RequestBody @Valid PasswordModel passwordModel) {
    5     //TODO
    6 }
    复制代码

    3、@ApiImplicitParams、@ApiImplicitParam:方法参数的说明

    复制代码
    @ApiImplicitParams:用在请求的方法上,包含一组参数说明
        @ApiImplicitParam:对单个参数的说明      
            name:参数名
            value:参数的汉字说明、解释
            required:参数是否必须传
            paramType:参数放在哪个地方
                · header --> 请求参数的获取:@RequestHeader
                · query --> 请求参数的获取:@RequestParam
                · path(用于restful接口)--> 请求参数的获取:@PathVariable
                · body(请求体)-->  @RequestBody User user
                · form(普通表单提交)     
            dataType:参数类型,默认String,其它值dataType="int"       
            defaultValue:参数的默认值
    复制代码

    举例:

    复制代码
     1 @ApiOperation(value="用户登录",notes="随边说点啥")
     2 @ApiImplicitParams({
     3         @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
     4         @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
     5         @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
     6 })
     7 @PostMapping("/login")
     8 public AjaxResult login(@RequestParam String mobile, @RequestParam String password,
     9                         @RequestParam Integer age){
    10     //TODO
    11     return AjaxResult.OK();
    12 }
    复制代码

    单个参数举例

    复制代码
    @ApiOperation("根据部门Id删除")
    @ApiImplicitParam(name="depId",value="部门id",required=true,paramType="query")
    @GetMapping("/delete")
    public AjaxResult delete(String depId) {
        //TODO
    }
    复制代码

     

    4、@ApiResponses、@ApiResponse:方法返回值的说明

    @ApiResponses:方法返回对象的说明
        @ApiResponse:每个参数的说明
            code:数字,例如400
            message:信息,例如"请求参数没填好"
            response:抛出异常的类

    举例:

    复制代码
     1 @ApiOperation(value = "修改密码", notes = "方法的备注说明,如果有可以写在这里")
     2 @ApiResponses({
     3         @ApiResponse(code = 400, message = "请求参数没填好"),
     4         @ApiResponse(code = 404, message = "请求路径找不到")
     5 })
     6 @PostMapping("/changepass")
     7 public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
     8         @RequestBody @Valid PasswordModel passwordModel) {
     9     //TODO
    10 }
    复制代码

    5、@ApiModel:用于JavaBean上面,表示一个JavaBean

    @ApiModel:用于JavaBean的类上面,表示此 JavaBean 整体的信息
        (这种一般用在post创建的时候,使用 @RequestBody 这样的场景,请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 )

    6. @ApiModelProperty:用在JavaBean的属性上面,说明属性的含义

    @ApiModel和 @ApiModelProperty举例:

    复制代码
    1 @ApiModel("修改密码所需参数封装类")
    2 public class PasswordModel
    3 {
    4     @ApiModelProperty("账户Id")
    5     private String accountId;
    6 //TODO
    7 }
    复制代码

    总结:API文档浏览地址

    配置好Swagger2并适当添加注解后,启动SpringBoot应用,
    访问http://localhost:8080/swagger-ui.html 即可浏览API文档。
    另外,我们需要为了API文档的可读性,适当的使用以上几种注解就可以。

     

     

    四、把Swagger2的API接口导入Postman

    1、访问http://localhost:8080/swagger-ui.html 文档的首页,复制下面这个地址

     

    2.打开postman-->import-->import Form Link

     

    转载:https://zhuanlan.zhihu.com/p/98075551

  • 相关阅读:
    win7通过配置怎么样ODBC数据源
    apache2.2 虚拟主机配置
    Matlab曲面拟合和插值
    查询记录rs.previous()使用
    阅读《平庸的世界》后感觉 (两)
    苹果公司的新的编程语言 Swift 高级语言()两--基本数据类型
    UVA 12075
    [LeetCode] Search a 2D Matrix [25]
    js 数组,字符串,JSON,bind, Name
    linux系统下怎么安装.deb文件?
  • 原文地址:https://www.cnblogs.com/javalinux/p/15691109.html
Copyright © 2020-2023  润新知