如何利用Swagger-UI自動生成接口文檔？

一、常用注解

Swagger-UI是HTML, Javascript, CSS的一個集合，可以動态地根據注解生成線上API文檔

@Api：用于修飾Controller類，生成Controller相關文檔資訊

@ApiOperation：用于修飾Controller類中的方法，生成接口方法相關文檔資訊

@ApiModel：用于修飾接口中的參數，生成接口參數相關文檔資訊

@ApiModelProperty：用于修飾實體類的屬性，當實體類是請求參數或傳回結果時，直接生成相關文檔資訊

二、 添加依賴

<!--Swagger-UI API文檔生産工具-->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.7.0</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.7.0</version>
</dependency>

           

三、編寫配置代碼

package com.smy.ouyangsong.config;

import org.springframework.context.annotation.Bean;
import org.springframework.boot.SpringBootConfiguration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2API文檔的配置
 */
@SpringBootConfiguration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //為目前包下controller生成API文檔
                .apis(RequestHandlerSelectors.basePackage("com.smy.ouyangsong.controller"))
                //為有@Api注解的Controller生成API文檔
//                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //為有@ApiOperation注解的方法生成API文檔
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("smy接口文檔")
                .description("Testing")
                .contact("ouyangsong")
                .version("1.0")
                .build();
    }
}

           

四、使用注解

• 給UsersController添加@Api(“操作user表”)注解

  

• 給usersController下的方法添加@ApiOperation注解

  

• 給model類添加@ApiModel注解，給屬性添加@ApiModelProperty注解

  

五、實作效果

• url：域名+端口+swagger-ui.html