• 使用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
  • 相关阅读:
    centos 7 -- Disk Requirements: At least 134MB more space needed on the / filesystem.
    DNS Server Centos 7
    生成report由Eamil定時寄出
    WRT 版本说明
    cisco linksys ea3500 刷机 openwrt
    [QNAP crontab 定時執行程式
    实例 编辑 .bashrc（不断更新）
    tar命令
    ls -l 显示年份
    git 丢弃本地代码时遇到的问题
  • 原文地址：https://www.cnblogs.com/ynyhl/p/13322432.html
Copyright © 2020-2023  润新知