Swagger2 shorthand

Some basic operations based on swagger2

- - Table of contents

1. Introduction to Swagger

The front-end and back-end are developed separately, and the back-end needs to write interface description documents, which is time-consuming. Swagger is a tool for generating normative documents for server interfaces and testing the interfaces.

2. Function

Generating normative documentation for server interfaces
Test the interface

3. Integration

Add dependencies in the api subproject (Swager2\Swagger UI)

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Create swagger configuration in api subproject (Java configuration method)

New config package, SwaggerConfig class


@Configuration
@EnableSwagger2 //启动Swagger2
public class SwaggerConfig {
    /*swagger 帮助我们生成帮助文档
     * 1.配置生成的文档信息
     * 2.配置生成的规则
     * Docket,封装接口文档信息
     * */
    public Docket getDocket() {
        //DocumentationType.SWAGGER_2 :指定文档风格
        /*
         * 如何获取一个接口、抽象类对象
         * 1.new 接口，需要在构造器后的{}实现接口中的所有抽象方法
         * 2.new 子类/实现类
         * 3.工厂模式
         * */

        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
        //创建封面信息对象
        apiInfoBuilder.title("《锋迷商城》接口说明")
                .description("此接口文档实现了.....")
                .version("v 2.0.1")
                .contact(new Contact("Mr.Suho", "www.cwaits.xyz", "[email protected]"));
        ApiInfo apiInfo = apiInfoBuilder.build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)//指定生成的文档封面信息：文档标题，版本。作者
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sh.controller"))
                .paths(PathSelectors.regex("/user/"))
                .build();
        return docket;
    }
}

test
- Start the SpringBoot application, visit: http://localhost:8080/swagger-ui.html

4. Swagger annotation description

swagger provides a set of annotations that can describe each interface in detail

@api (class annotation ), add this annotation to the controller class to describe the controller
```
@Api(value = "实现用户登录，注册功能",tags = "用户管理")
```

@ApiImplicitiParams and @ApiImplicitiParam (method annotations) , which describe the parameters of the interface method

   @ApiImplicitParams({
            @ApiImplicitParam(dataType ="String",name = "username",value = "用户登录账号",required = true),
            @ApiImplicitParam(dataType ="String",name = "pwd",value = "用户登录密码",required = false),
    })
    @RequestMapping(value = "/login",method = RequestMethod.GET)
    public ResultVo login(String name, String pwd){
       return userService.checkLogin(name,pwd);
    }

@ApiOperation (method annotation) , explaining the role of the interface method

 @ApiOperation("用户登录接口")
   @RequestMapping(value = "/login",method = RequestMethod.GET)
    public ResultVo login(String name, String pwd){
       return userService.checkLogin(name,pwd);
    }

@ApiModel and @ApiModelProperty , when the interface parameters and return values are object types, add annotations to the entity class

@ApiModel(value = "ResultVO对象",description = "封装接口返回给前端的数据")
public class ResultVo {
    //响应给前端的状态码
    @ApiModelProperty(value = "响应状态码",dataType = "int")
    private Integer code;
    //响应给前端的提示信息
    @ApiModelProperty("响应提示信息")
    private String msg;
    //响应给前端的数据
    @ApiModelProperty("响应数据")
    private Object data;
}

@ApiIgnore , interface method annotation, the method added with this annotation will not be generated into the interface document

 @ApiIgnore
    @RequestMapping(value = "/login",method = RequestMethod.GET)
    public ResultVo login(String name, String pwd){
       return userService.checkLogin(name,pwd);
    }

5. Swagger-ui plugin

Import plugin dependencies

   <!--swagger-ui 插件-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

Documentation access:http://ip:port/doc.html
- http://localhost:8080/doc.html