接口文檔管理系列 Spring MVC架構整合Swagger

• • 環境
  • 引入依賴
  • 配置web.xml
  • 修改spring MVC應用上下文配置檔案
  • 碼代碼
  • • Swagger配置類
  • 啟動測試
  • swagger注解
  • • @Api
    • @ApiImplicitParams
    • @ApiResponses
    • @ApiModel
  • 一個OpenAPI的接口
  • 導讀

環境

元件	版本
java	1.8
maven	3.6.3
idea	2020.1
springfox-swagger	2.9.2
knife4j	2.0.2

引入依賴

pom.xml

<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>
        
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.2</version>
        </dependency>

           

配置web.xml

WEB-INF/web.xml

修改

Spring MVC Servle

t配置項

<servlet>
        <servlet-name>spring-web-mvc</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>classpath:applicationContext-MVC.xml</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>spring-web-mvc</servlet-name>
        <url-pattern>/</url-pattern>
        <url-pattern>/v2/api-docs</url-pattern>
        <url-pattern>/swagger-resources</url-pattern>
        <url-pattern>/swagger-resources/configuration/security</url-pattern>
        <url-pattern>/swagger-resources/configuration/ui</url-pattern>

    </servlet-mapping>

           

修改spring MVC應用上下文配置檔案

我這裡是

src\main\resources\applicationContext-MVC.xml

<mvc:default-servlet-handler/>

    <mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
    <mvc:resources location="classpath:/META-INF/resources/" mapping="doc.html"/>
    <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>

    <bean id="SwaggerConfig" class="cn.Swagger.SwaggerConfiguration"></bean>
           

碼代碼

Swagger配置類

/**
 * Swagger配置類
 */
@Component
@Configuration
@EnableSwagger2
@EnableWebMvc
/*
  這個注解是在SpringBoot項目中使用的AutoConfig
   @EnableKnife4j
    在Spring MVC項目中不要使用
 */
@ComponentScan("cn.Controller")
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.Controller"))
//              .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//這是注意的代碼 在Action上加注解@Api
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger-bootstrap-ui RESTful APIs")
                .description("swagger-bootstrap-ui")
                .termsOfServiceUrl("http://localhost:8080/")
                .contact("[email protected]")
                .version("1.0")
                .build();
    }
}
           

啟動測試

swagger注解

@Api

@Api(tags = {"pet操作"})
class

@ApiOperation(value = "新增一個pet" , tags = {"pet操作","新增pet"})
function
           

标簽，可以是多個

接口按照标簽歸類，也就是說接口可能會在多個标簽歸類中出現

@ApiImplicitParams

聲明接口請求的資訊

參數類型，說明，執行個體

@ApiImplicitParams(value =@ApiImplicitParam(example = "{id: 1 , name: 白貓}"))
function

           

@ApiResponses

@ApiResponses(value = {
            @ApiResponse(code = 405, message = "Invalid input" ,
                    examples = @Example({@ExampleProperty(mediaType = "String",value = "抱歉，你請求失敗了")})),
            @ApiResponse(code = 200 ,  message = "接口請求完成" ,
                    examples = @Example({@ExampleProperty(mediaType = "Integer" , value = "1") ,
                               @ExampleProperty(mediaType = "String",value = "tom") })
            )})
           

@ApiModel

@ApiModel(description = "pet model class")
public class Pet implements Serializable {
  @JsonProperty("id")
  @ApiModelProperty(notes = "pet編号,請輸入數字",value = "pet ID",name = "pet 編号",required = true,example = "00001")
  private Integer id = null;

  @ApiModelProperty(notes = "pet名字，請輸入中文",value = "pet name" , name = "pet 名字" , required = true , example = "黑貓")
  @JsonProperty("name")
  private String name = null;

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public Integer getId() {
    return id;
  }

  public void setId(Integer id) {
    this.id = id;
  }
}
           

model上的聲明資訊會應用在接口上面

一個OpenAPI的接口

使用ResponseEntity來包裝傳回資料

@ApiOperation(value = "新增一個pet" , tags = {"pet操作","新增pet"})
    @ApiImplicitParams(value =@ApiImplicitParam(example = "{id: 1 , name: 白貓}"))
    @PostMapping("add")
    public ResponseEntity<Pet> add(Pet model){

        return new ResponseEntity(model, HttpStatus.OK);
    }

           

springdoc官網

導讀

接口文檔管理系列 OpenAPI規範及Swagger工具集

接口文檔管理系列 Springboot內建springdoc