spring-boot-route (5) Integrate Swagger to generate interface documents

At present, most companies have adopted the development model of separation of front and back ends. In order to solve the communication problem between front and back end personnel, back end personnel will choose to use swagger2 to generate corresponding interface documents when developing interfaces. Function, which can effectively solve the problem of difficult communication between front-end and back-end personnel.

Below we use SpringBoot combined with swagger2 to generate Restful API documentation.

One build the project and introduce dependencies

Create a new spring-boot-swaagerproject and introduce the dependency of swaper2. Since the ui of swagger2 is not very beautiful, we will use the open source swagger-bootstrap-uias the ui here.

Introduce dependencies

<!-- swaager2依赖 -->    
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- swaager2ui -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

Configure swagger related information in the project

@Configuration
@EnableSwagger2
public class configuration {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.javatrip.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                // 标题
                .title("某某项目接口文档")
                // 描述
                .description("swagger2接口文档使用演示")
                // 版本
                .version("1.0")
                // 许可证
                .license("MIT")
                // 许可证地址
                .licenseUrl("www.xx.com")
                // 服务端地址
                .termsOfServiceUrl("https://www.cnblogs.com/zhixie/")
                // 联系信息
                .contact(new Contact("java旅途","https://www.cnblogs.com/zhixie/","[email protected]"))
                .build();
    }
}

Access path, view the generated effect

The ui used in the article, the interface document address is ip:port/doc.html, the generated document information is as follows:

Two writing Restful interface

New entity class

@ApiModel("用户实体类")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Person {
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty(value = "年龄")
    private int age;
}

New Restful interface

@Api(tags = "用户接口")
@RestController
@RequestMapping("person")
public class PersonController {

    @ApiOperation(value = "获取用户列表",notes = "根据name获取用户列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",value = "用户姓名",dataType = "String",required = true),
            @ApiImplicitParam(name = "age",value = "年龄",dataType = "int",required = true)
    })
    @GetMapping("/{name}")
    public Person getPerson(@PathVariable("name") String name,@RequestParam int age){
        return new Person(name,age);
    }

    @ApiOperation(value = "新增用户",notes = "根据用户实体类新增用户")
    @ApiImplicitParam(name = "person",value = "用户实体类",dataType = "Person",required = true)
    @PostMapping("add")
    public int addPerson(@RequestBody Person person){
        if(StringUtils.isEmpty(person)){
            return -1;
        }
        return 1;
    }

    @ApiOperation(value = "更新用户信息",notes = "根据用户实体更新用户信息")
    @ApiImplicitParam(name = "person",value = "用户实体类",dataType = "Person",required = true)
    @PutMapping("update")
    public int updatePerson(@RequestBody Person person){
        if(StringUtils.isEmpty(person)){
            return -1;
        }
        return 1;
    }

    @ApiOperation(value = "删除用户信息",notes = "根据用户名删除用户信息")
    @ApiImplicitParam(name = "name",value = "用户姓名",dataType = "String",required = true)
    @DeleteMapping("/{name}")
    public int deletePerson(@PathVariable(name = "name") String name){
        if(StringUtils.isEmpty(name)){
            return -1;
        }
        return 1;
    }
}

Introduction to three swagger documents

I just used the diagram to show it directly, so it’s more intuitive to look at

The swagger2 annotation corresponds to the form of expression on the document as above. swagger2 supports online debugging, open a specific interface, fill in the corresponding parameters according to the prompts, and click send to return the response result.

This is the fifth article in the spring-boot-route series. The articles in this series are relatively simple. The main purpose is to help students who are new to Spring Boot have a systematic understanding. This article has been included in my github , welcome friends star!

github：https://github.com/binzh303/spring-boot-route

Pay attention, don't get lost

If you feel good essays, welcome attention , thumbs up , collection , your support is my creative power, thank you.

If there is a problem with the writing of the article, please don't be stingy. Please leave a message and point it out. I will check and modify it in time.

If you want to know me more deeply, you can search for " Java Journey " on WeChat to follow. Reply " 1024 " to get learning videos and exquisite e-books. Push technical articles on time at 7:30 every day, so that you are not alone on your way to work, and there are monthly book delivery activities to help you improve your hard power!