Spring Boot從入門到精通-整合swagger

摘要： 現在我們的專案中已經有了一個可供外部呼叫的rest api介面，隨著專案的擴充套件以後會有越來越多的介面，這個時候就需要同時對外部提供關於介面的詳細說明文件，而swagger幫我們使用很少的時間就可以構建出一套介面文件。 首先在pom.xml中引用swagger所需的依賴。 ...

現在我們的專案中已經有了一個可供外部呼叫的rest api介面，隨著專案的擴充套件以後會有越來越多的介面，這個時候就需要同時對外部提供關於介面的詳細說明文件，而swagger幫我們使用很少的時間就可以構建出一套介面文件。

• 首先在pom.xml中引用swagger所需的依賴。

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<scope>compile</scope>
 </dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
 </dependency>

• 然後在程式碼中開啟swagger

@Configuration
@EnableSwagger2
/** 是否開啟swagger **/
//@ConditionalOnExpression("'${swagger.enable}' == 'true'") 可以動態控制的開關，之後再使用
public class SwaggerConfig {


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

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springt boot 從入門到精通 api")
.description("springt boot 從入門到精通 api")
.termsOfServiceUrl("https://www.jianshu.com/u/c9deb1bda6ce")
.contact("https://www.jianshu.com/u/c9deb1bda6ce")
.version("1.0.0")
.build();
}

}

這一步完成之後，啟動專案，開啟 localhost:8080/swagger-ui.html#/就可以看到swagger的介面了，並且我們寫好的那個介面也已經躺在那裡等我們的呼叫。

swagger還有更多的註解幫助我們完善介面文件。

從原始碼中可以看到swagger提供了這麼多註解，下面我們將常用的幾個進行講解：

@Api

@Api(value = "註解在controller類上", description = "註解在controller類上")

@ApiOperation

@ApiOperation(value = "具體介面描述，寫在controller的方法上, notes = "具體介面描述，寫在controller的方法上")

@ApiModelProperty

@ApiModelProperty(value = "寫在介面對應的實體類的屬性上", example = "值")