[TOC] # 依賴 ~~~ <!-- swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency> ~~~ # 常用注解 ~~~ Api：修飾整個類，描述Controller的作用 ApiOperation：描述一個類的一個方法，或者說一個接口 ApiParam：單個參數描述 ApiModel：用對象來接收參數 ApiProperty：用對象接收參數時，描述對象的一個字段 ApiResponse：HTTP響應其中1個描述 ApiResponses：HTTP響應整體描述 ApiIgnore：使用該注解忽略這個API ApiError ：發生錯誤返回的信息 ApiImplicitParam：一個請求參數 ApiImplicitParams：多個請求參數 ~~~ ## Api標記 默認情況,只會掃描具有@Api注解的類 Api 用在類上，說明該類的作用。可以標記一個Controller類做為swagger 文檔資源，使用方式： ~~~ @Api(value = "/user", description = "Operations about user") ~~~ 與Controller注解并列使用。 屬性配置： | 屬性名稱 | 備注 | | --- | --- | | value | url的路徑值 | | tags | 如果設置這個值、value的值會被覆蓋 | | description | 對api資源的描述 | | basePath | 基本路徑可以不配置 | | position | 如果配置多個Api 想改變顯示的順序位置 | | produces | For example, "application/json, application/xml" | | consumes | For example, "application/json, application/xml" | | protocols | Possible values: http, https, ws, wss. | | authorizations | 高級特性認證時配置 | | hidden | 配置為true 將在文檔中隱藏 | 在SpringMvc中的配置如下： ~~~ @Controller @RequestMapping(value = "/api/pet", produces = {APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE}) @Api(value = "/pet", description = "Operations about pets") public class PetController { } ~~~ ~~~ @Api(value = "消息" ,description = "用戶接口", protocols = "http") @RestController @RequestMapping("user") public class UserController { ~~~  ## ApiOperation標記 ApiOperation：用在方法上，說明方法的作用，每一個url資源的定義,使用方式： ~~~ @ApiOperation( value = "Find purchase order by ID", notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions", response = Order, tags = {"Pet Store"}) ~~~ 與Controller中的方法并列使用。 屬性配置： | 屬性名稱 | 備注 | | --- | --- | | value | url的路徑值 | | tags | 如果設置這個值、value的值會被覆蓋 | | description | 對api資源的描述 | | basePath | 基本路徑可以不配置 | | position | 如果配置多個Api 想改變顯示的順序位置 | | produces | For example, "application/json, application/xml" | | consumes | For example, "application/json, application/xml" | | protocols | Possible values: http, https, ws, wss. | | authorizations | 高級特性認證時配置 | | hidden | 配置為true 將在文檔中隱藏 | | response | 返回的對象 | | responseContainer | 這些對象是有效的 "List", "Set" or "Map".，其他無效 | | httpMethod | "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH" | | code | http的狀態碼 默認 200 | | extensions | 擴展屬性 | 在SpringMvc中的配置如下： ~~~kotlin @RequestMapping(value = "/order/{orderId}", method = GET) @ApiOperation( value = "Find purchase order by ID", notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions", response = Order.class, tags = { "Pet Store" }) public ResponseEntity<Order> getOrderById(@PathVariable("orderId") String orderId) throws NotFoundException { Order order = storeData.get(Long.valueOf(orderId)); if (null != order) { return ok(order); } else { throw new NotFoundException(404, "Order not found"); } } ~~~ ## ApiParam標記 ApiParam請求屬性,使用方式 ~~~kotlin public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true) User user) ~~~ 與Controller中的方法并列使用。 屬性配置： | 屬性名稱 | 備注 | | --- | --- | | name | 屬性名稱 | | value | 屬性值 | | defaultValue | 默認屬性值 | | allowableValues | 可以不配置 | | required | 是否屬性必填 | | access | 不過多描述 | | allowMultiple | 默認為false | | hidden | 隱藏該屬性 | | example | 舉例子 | 在SpringMvc中的配置如下： ~~~kotlin public ResponseEntity<Order> getOrderById( @ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true) @PathVariable("orderId") String orderId) ~~~ ## ApiResponse ApiResponse：響應配置，使用方式： ~~~ @ApiResponse(code = 400, message = "Invalid user supplied") ~~~ 與Controller中的方法并列使用。 屬性配置： | 屬性名稱 | 備注 | | --- | --- | | code | http的狀態碼 | | message | 描述 | | response | 默認響應類 Void | | reference | 參考ApiOperation中配置 | | responseHeaders | 參考 ResponseHeader 屬性配置說明 | | responseContainer | 參考ApiOperation中配置 | 在SpringMvc中的配置如下： ~~~kotlin @RequestMapping(value = "/order", method = POST) @ApiOperation(value = "Place an order for a pet", response = Order.class) @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") }) public ResponseEntity<String> placeOrder( @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) { storeData.add(order); return ok(""); } ~~~ ## ApiResponses ApiResponses：響應集配置，使用方式： ~~~ @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") }) ~~~ 與Controller中的方法并列使用。 屬性配置： | 屬性名稱 | 備注 | | --- | --- | | value | 多個ApiResponse配置 | 在SpringMvc中的配置如下： ~~~kotlin @RequestMapping(value = "/order", method = POST) @ApiOperation(value = "Place an order for a pet", response = Order.class) @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") }) public ResponseEntity<String> placeOrder( @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) { storeData.add(order); return ok(""); } ~~~ ## ResponseHeader > 響應頭設置，使用方法 ~~~kotlin @ResponseHeader(name="head1",description="response head conf") ~~~ 與Controller中的方法并列使用。 屬性配置： | 屬性名稱 | 備注 | | --- | --- | | name | 響應頭名稱 | | description | 頭描述 | | response | 默認響應類 Void | | responseContainer | 參考ApiOperation中配置 | 在SpringMvc中的配置如下： ~~~ @ApiModel(description = "群組") ~~~ ## 其他 * @ApiImplicitParams：用在方法上包含一組參數說明； * @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數的各個方面 * paramType：參數放在哪個地方 * name：參數代表的含義 * value：參數名稱 * dataType： 參數類型，有String/int，無用 * required ： 是否必要 * defaultValue：參數的默認值 * @ApiResponses：用于表示一組響應； * @ApiResponse：用在@ApiResponses中，一般用于表達一個錯誤的響應信息； * code： 響應碼(int型)，可自定義 * message：狀態碼對應的響應信息 * @ApiModel：描述一個Model的信息（這種一般用在post創建的時候，使用@RequestBody這樣的場景，請求參數無法使用@ApiImplicitParam注解進行描述的時候； * @ApiModelProperty：描述一個model的屬性。 paramType說的是你的參數類型，path說明參數是在url路徑上`/a/b/id`，query是說參數在get方法的查詢參數上`/a/b/c?id=1&name=tom`，這個就是swagger會影響參數接收的原因. | | | | --- | --- | | name | 接收參數名 | | value | 接收參數的意義描述 | | required | 參數是否必填值為 true 或者 false| | dataType | 參數的數據類型只作為標志說明，并沒有實際驗證| | paramType | 查詢參數類型，其值 path 以地址的形式提交數據, query 直接跟參數完成自動映射 body 以流的形式提交僅?支持 POST, header 參數在 request headers 里邊提交, form 以 form 表單的形式提交 僅?支持 POST| | defaultValue | 默認值 | --- 如果是上傳文件的話，需要把`@ApiImplicitParam`中的`dataType`屬性配置為`__File`否則在swagger中會顯示為文本框而不是上傳按鈕 # 配置 basePackage里面的包名要改下,寫哪里就掃哪里,可以寫控制器下的 ~~~ import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; 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; /** * Swagger 配置文件 */ @Configuration public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.swagger.two")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("SpringBoot利用Swagger構建API文檔") .description("使用RestFul風格, 創建人：知了一笑") .termsOfServiceUrl("https://github.com/cicadasmile") .version("version 1.0") .build(); } } ~~~ ## 所有的添加進去 配置文件,有了這個,不寫@EnableSwagger2這個也可以 ~~~ swagger: enabled: true ~~~ * @Configuration，啟動時加載此類 * @EnableSwagger2，表示此項?目啟?用 Swagger Api注解 ~~~ import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfig { /** * 創建一個Docket對象 * 調用select()方法， * 生成ApiSelectorBuilder對象實例，該對象負責定義外漏的API入口 * 通過使用RequestHandlerSelectors和PathSelectors來提供Predicate，在此我們使用any()方法，將所有API都通過Swagger進行文檔管理 * @return */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } //可以看ApiInfo的詳細信息 private ApiInfo apiInfo() { return new ApiInfoBuilder() //標題 .title("Spring Boot中使用Swagger2構建RESTful APIs") //簡介 .description("") //服務條款 .termsOfServiceUrl("") //作者個人信息 .contact(new Contact("chenguoyu","","chenguoyu_sir@163.com")) //版本 .version("1.0") .build(); } } ~~~ # 啟動類添加注解 @EnableSwagger2可以在其他地方配置 ~~~ @EnableSwagger2 @SpringBootApplication public class SwaggerApplication { public static void main(String[] args) { SpringApplication.run(SwaggerApplication.class,args) ; } } ~~~ 打開`http://localhost:8080/swagger-ui.html` # 增刪改查案例 ## 添加用戶 ~~~ @ApiOperation(value="添加用戶", notes="創建新用戶") @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User") @RequestMapping(value = "/addUser", method = RequestMethod.POST) public ResponseEntity addUser (@RequestBody User user){ ~~~ ## 用戶列表 ~~~ @ApiOperation(value="用戶列表", notes="查詢用戶列表") @RequestMapping(value = "/getUserList", method = RequestMethod.GET) public ResponseEntity getUserList (){ ~~~ ## 用戶查詢 ~~~ @ApiOperation(value="用戶查詢", notes="根據ID查詢用戶") @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Integer", paramType = "path") @RequestMapping(value = "/getUserById/{id}", method = RequestMethod.GET) public ResponseEntity getUserById (@PathVariable(value = "id") Integer id){ ~~~ ## 更新用戶 ~~~ @ApiOperation(value="更新用戶", notes="根據Id更新用戶信息") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long",paramType = "path"), @ApiImplicitParam(name = "user", value = "用戶對象user", required = true, dataType = "User") }) @RequestMapping(value = "/updateById/{id}", method = RequestMethod.PUT) public ResponseEntity<JsonResult> updateById (@PathVariable("id") Integer id, @RequestBody User user){ ~~~ ## 刪除用戶 ~~~ @ApiOperation(value="刪除用戶", notes="根據id刪除指定用戶") @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long", paramType = "path") @RequestMapping(value = "/deleteById/{id}", method = RequestMethod.DELETE) public ResponseEntity<JsonResult> deleteById (@PathVariable(value = "id") Integer id){ ~~~ # 404解決 ~~~ <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${swagger.version}</version> </dependency> ~~~ **配置靜態訪問資源** ~~~ @Configuration @EnableWebMvc public class WebMvcConfigurerConfig implements WebMvcConfigurer { private CorsConfiguration buildConfig() { CorsConfiguration corsConfiguration = new CorsConfiguration(); corsConfiguration.addAllowedOrigin("*"); corsConfiguration.setAllowCredentials(true); corsConfiguration.addAllowedHeader("*"); corsConfiguration.addAllowedMethod("*"); return corsConfiguration; } @Bean public CorsFilter corsFilter() { UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration("/**", buildConfig()); return new CorsFilter(source); } @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } } ~~~ # 更改UI 由于個人感覺原生的swagger-ui不太好看,更改UI [https://doc.xiaominfo.com/guide/](https://doc.xiaominfo.com/guide/) ~~~ <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.3</version> </dependency> ~~~ 配置靜態訪問資源 ~~~ @Configuration public class WebMvcConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { // 解決 swagger-ui.html 404報錯 registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); // 解決 doc.html 404 報錯 registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/"); } } ~~~ # 離線文檔 **使用Swagger2Markup導出swagger2文檔** ~~~ <!--swagger靜態化輸出依賴--> <dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.3</version> </dependency> ~~~ ~~~ <!--swagger靜態化插件 先執行測試類生成.adoc文件再運行maven命令 asciidoctor:process-asciidoc生成html--> <plugin> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.6</version> <configuration> <sourceDirectory>./docs/asciidoc/generated</sourceDirectory> <outputDirectory>./docs/asciidoc/html</outputDirectory> <headerFooter>true</headerFooter> <doctype>book</doctype> <backend>html</backend> <sourceHighlighter>coderay</sourceHighlighter> <attributes> <!--菜單欄在左邊--> <toc>left</toc> <!--多標題排列--> <toclevels>3</toclevels> <!--自動打數字序號--> <sectnums>true</sectnums> </attributes> </configuration> </plugin> ~~~ **完整的pom** ~~~ <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <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> <!--導出到markdown文件的依賴 --> <dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.3</version> </dependency> <dependency> <groupId>nl.jworks.markdown_to_asciidoc</groupId> <artifactId>markdown_to_asciidoc</artifactId> <version>1.1-sources</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> <exclusions> <exclusion> <groupId>org.junit.vintage</groupId> <artifactId>junit-vintage-engine</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>junit</groupId> <artifactId>junit</artifactId> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> <!--swagger靜態化插件 先執行測試類生成.adoc文件再運行maven命令 asciidoctor:process-asciidoc生成html--> <plugin> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.6</version> <configuration> <sourceDirectory>./docs/asciidoc/generated</sourceDirectory> <outputDirectory>./docs/asciidoc/html</outputDirectory> <headerFooter>true</headerFooter> <doctype>book</doctype> <backend>html</backend> <sourceHighlighter>coderay</sourceHighlighter> <attributes> <!--菜單欄在左邊--> <toc>left</toc> <!--多標題排列--> <toclevels>3</toclevels> <!--自動打數字序號--> <sectnums>true</sectnums> </attributes> </configuration> </plugin> </plugins> </build> </project> ~~~ **寫一個測試類** ~~~ import io.github.swagger2markup.GroupBy; import io.github.swagger2markup.Language; import io.github.swagger2markup.Swagger2MarkupConfig; import io.github.swagger2markup.Swagger2MarkupConverter; import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder; import io.github.swagger2markup.markup.builder.MarkupLanguage; import org.junit.Test; import org.junit.runner.RunWith; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.test.context.junit4.SpringRunner; import java.net.URL; import java.nio.file.Paths; @RunWith(SpringRunner.class) @SpringBootTest public class ApplicationIntfTests { /** * 生成AsciiDocs格式文檔 * @throws Exception */ @Test public void generateAsciiDocs() throws Exception { // 輸出Ascii格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")) .withConfig(config) .build() .toFolder(Paths.get("./docs/asciidoc/generated")); } /** * 生成Markdown格式文檔 * @throws Exception */ @Test public void generateMarkdownDocs() throws Exception { // 輸出Markdown格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")) .withConfig(config) .build() .toFolder(Paths.get("./docs/markdown/generated")); } /** * 生成Confluence格式文檔 * @throws Exception */ @Test public void generateConfluenceDocs() throws Exception { // 輸出Confluence使用的格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")) .withConfig(config) .build() .toFolder(Paths.get("./docs/confluence/generated")); } /** * 生成AsciiDocs格式文檔,并匯總成一個文件 * @throws Exception */ @Test public void generateAsciiDocsToFile() throws Exception { // 輸出Ascii到單文件 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")) .withConfig(config) .build() .toFile(Paths.get("./docs/asciidoc/generated/all")); } /** * 生成Markdown格式文檔,并匯總成一個文件 * @throws Exception */ @Test public void generateMarkdownDocsToFile() throws Exception { // 輸出Markdown到單文件 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")) .withConfig(config) .build() .toFile(Paths.get("./docs/markdown/generated/all")); } } ~~~ 啟動項目,拿到json文件的地址,拿到之后關閉項目,不然之后允許測試的時候會報端口被占用 運行步驟中的五個Test,如果報docs/markdown文件夾不存在,請自己手動建文件夾;不出意外的話generated會生成.adoc文件 ~~~ . ├── asciidoc │?? └── generated │?? ├── all.adoc │?? ├── definitions.adoc │?? ├── overview.adoc │?? ├── paths.adoc │?? └── security.adoc ├── confluence │?? └── generated │?? ├── definitions.txt │?? ├── overview.txt │?? ├── paths.txt │?? └── security.txt └── markdown └── generated ├── all.md ├── definitions.md ├── overview.md ├── paths.md └── security.md ~~~ 運行maven命令asciidoctor:process-asciidoc生成html ~~~ mvn asciidoctor:process-asciidoc ~~~ 大功告成,訪問all.html即可 ~~~ ├── asciidoc │?? ├── generated │?? │?? ├── all.adoc │?? │?? ├── definitions.adoc │?? │?? ├── overview.adoc │?? │?? ├── paths.adoc │?? │?? └── security.adoc │?? └── html │?? ├── all.html │?? ├── definitions.html │?? ├── overview.html │?? ├── paths.html │?? └── security.html ├── confluence │?? └── generated │?? ├── definitions.txt │?? ├── overview.txt │?? ├── paths.txt │?? └── security.txt └── markdown └── generated ├── all.md ├── definitions.md ├── overview.md ├── paths.md └── security.md ~~~ # 注解總結 ~~~ @Api：用在請求的類上，表示對類的說明 tags="說明該類的作用，可以在UI界面上看到的注解" value="該參數沒什么意義，在UI界面上也看到，所以不需要配置" @ApiOperation：用在請求的方法上，說明方法的用途、作用 value="說明方法的用途、作用" notes="方法的備注說明" @ApiImplicitParams：用在請求的方法上，表示一組參數說明 @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數的各個方面 name：參數名 value：參數的漢字說明、解釋 required：參數是否必須傳 paramType：參數放在哪個地方 · header --> 請求參數的獲取：@RequestHeader · query --> 請求參數的獲取：@RequestParam · path（用于restful接口）--> 請求參數的獲取：@PathVariable · body（不常用） · form（不常用） dataType：參數類型，默認String，其它值dataType="Integer" defaultValue：參數的默認值 @ApiResponses：用在請求的方法上，表示一組響應 @ApiResponse：用在@ApiResponses中，一般用于表達一個錯誤的響應信息 code：數字，例如400 message：信息，例如"請求參數沒填好" response：拋出異常的類 @ApiModel：用于響應類上，表示一個返回響應數據的信息 （這種一般用在post創建的時候，使用@RequestBody這樣的場景， 請求參數無法使用@ApiImplicitParam注解進行描述的時候） @ApiModelProperty：用在屬性上，描述響應類的屬性 ~~~ 1、@Api：用在請求的類上，說明該類的作用 ? ? ?tags="說明該類的作用" ? ? ?value="該參數沒什么意義，所以不需要配置" 示例： ~~~ @Api(tags="APP用戶注冊Controller") ~~~ 2、@ApiOperation：用在請求的方法上，說明方法的作用 @ApiOperation："用在請求的方法上，說明方法的作用" ? ? value="說明方法的作用" ? ? notes="方法的備注說明" 示例： ~~~ @ApiOperation(value="用戶注冊",notes="手機號、密碼都是必輸項，年齡隨邊填，但必須是數字") ~~~ 3、@ApiImplicitParams：用在請求的方法上，包含一組參數說明 ? ? ?@ApiImplicitParams：用在請求的方法上，包含一組參數說明 ? ? ?@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一個請求參數的配置信息 ? ? ?? ? ? ? ? name：參數名 ? ? ? ? value：參數的漢字說明、解釋 ? ? ? ? required：參數是否必須傳 ? ? ? ? paramType：參數放在哪個地方 ? ? ? ? ? ? · header --> 請求參數的獲取：@RequestHeader ? ? ? ? ? ? · query --> 請求參數的獲取：@RequestParam ? ? ? ? ? ? · path（用于restful接口）--> 請求參數的獲取：@PathVariable ? ? ? ? ? ? · body（不常用） ? ? ? ? ? ? · form（不常用） ? ? ? ? ? ? dataType：參數類型，默認String，其它值dataType="Integer" ? ? ?? ? ? ? ? defaultValue：參數的默認值 示列： ~~~java @ApiImplicitParams({ @ApiImplicitParam(name="mobile",value="手機號",required=true,paramType="form"),? ? @ApiImplicitParam(name="password",value="密碼",required=true,paramType="form"),? ? @ApiImplicitParam(name="age",value="年齡",required=true,paramType="form",dataType="Integer")}) ~~~ 4、@ApiResponses：用于請求的方法上，表示一組響應 ? ? ?@ApiResponses：用于請求的方法上，表示一組響應 ? ? ?@ApiResponse：用在@ApiResponses中，一般用于表達一個錯誤的響應信息 ? ? ? ? code：數字，例如400 ? ? ? ? message：信息，例如"請求參數沒填好" ? ? ? ? response：拋出異常的類 示例： ~~~java @ApiOperation(value = "select1請求",notes = "多個參數，多種的查詢參數類型")@ApiResponses({? ? @ApiResponse(code=400,message="請求參數沒填好"),? ? @ApiResponse(code=404,message="請求路徑沒有或頁面跳轉路徑不對")}) ~~~ 5、@ApiModel：用于響應類上，表示一個返回響應數據的信息 ? ? ?@ApiModel：用于響應類上，表示一個返回響應數據的信息 ? ? ? ? ? ? （這種一般用在post創建的時候，使用@RequestBody這樣的場景， ? ? ? ? ? ? 請求參數無法使用@ApiImplicitParam注解進行描述的時候） ? ? ?@ApiModelProperty：用在屬性上，描述響應類的屬性 示例: ~~~java import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import java.io.Serializable; @ApiModel(description= "返回響應數據") public class RestMessage implements Serializable{ ? ? @ApiModelProperty(value = "是否成功") ? ? private boolean success=true; ? ? @ApiModelProperty(value = "返回對象") ? ? private Object data; ? ? @ApiModelProperty(value = "錯誤編號") ? ? private Integer errCode; ? ? @ApiModelProperty(value = "錯誤信息") ? ? private String message; ? ? /* getter/setter */ } ~~~