SpringBoot+Swagger+IDEA⽣成API接⼝⽂档导出PDF和HTML 1.pom⽂件导⼊swagger依赖
1 <dependency>
2 <groupId>io.springfox</groupId>
3 <artifactId>springfox-swagger2</artifactId>
4 <version>2.6.1</version>
5 </dependency>
6 <dependency>
7 <groupId>io.springfox</groupId>
8 <artifactId>springfox-swagger-ui</artifactId>
9 <version>2.6.1</version>
10 </dependency>
swagger依赖
2.添加配置⽂件
1 @Configuration
2 @EnableSwagger2
3public class SwaggerConfig implements WebMvcConfigurer {
4
5 @Override
6public void addResourceHandlers(ResourceHandlerRegistry registry) {
7 registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
8 registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
9 registry.addResourceHandler("/swagger/**").addResourceLocations("classpath:/static/swagger/");
10 }
11
12
13 @Bean
14public Docket createRestApi() {
15return new Docket(DocumentationType.SWAGGER_2)
16 .apiInfo(apiInfo())
17 .select()
18//加了ApiOperation注解的类，才⽣成接⼝⽂档
19 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
20//包下的类，才⽣成接⼝⽂档
21 .apis(RequestHandlerSelectors.basePackage("com.huawei.ller"))
22 .paths(PathSelectors.any())
23 .build()
24//在⽣产环境需要把swagger关闭，enable(false)
25 .enable(true);
26 }
27
28private ApiInfo apiInfo() {pdf转html
29return new ApiInfoBuilder()
30 .title("XXX公司")
31 .description("XXXCRM-API⽂档")
32 .termsOfServiceUrl("www.baidu/")
33 .version("1.0")
34 .build();
35 }
36 }
SwaggerConfig
3.在contrallor和vo(对象等)中加⼊注解
1 @Api：修饰整个类，描述Controller的作⽤
2 @ApiOperation：描述⼀个类的⼀个⽅法，或者说⼀个接⼝
3 @ApiParam：单个参数描述
4 @ApiModel：⽤对象来接收参数，描述整个对象的信息
5 @ApiProperty：⽤对象接收参数时，描述对象的⼀个属性
6 @ApiResponse：HTTP响应其中1个描述
7 @ApiResponses：HTTP响应整体描述
8 @ApiIgnore：使⽤该注解忽略这个API
9 @ApiError ：发⽣错误返回的信息
10 @ApiImplicitParam：⼀个请求参数描述
11 @ApiImplicitParams：多个请求参数描述
swagger常⽤注解
1 @Controller
2 @RequestMapping(value = "/users", produces = MediaType.APPLICATION_JSON_VALUE)
3 @Api(value = "/users", tags = "Users", description = "Operations about user")
4public class UserController {
5 UserRepository userRepository = new UserRepository();
6
7static class UserRepository extends MapBackedRepository<String, User> {
8 }
9
10 @RequestMapping(method = POST)
11 @ResponseBody
12 @ApiOperation(value = "Create user", notes = "This can only be done by the logged in user.")
13public ResponseEntity<User> createUser(
14 @RequestBody
15 @ApiParam(value = "Created user object", required = true) User user) {
16
17 userRepository.add(user);
18return new ResponseEntity<User>(user, HttpStatus.OK);
19 }
20
21 }
contrallor注解
1public class User {
2 @ApiModelProperty(value = "⽤户名称")
3private String username;
4 @ApiModelProperty(value = "电⼦邮件")
5private String email;
6private String password;
7private String phone;
8 }
对象注解
5.将下载的⽂件命名为 swagger.json 并放到 maven打包⽂件夹下
7.pom⽂件加⼊swagger2markup的属性和相关配置
1 <properties>
2 <swagger2markup.version>1.2.0</swagger2markup.version>
3 <asciidoctor.input.directory>${project.basedir}/src/docs/asciidoc</asciidoctor.input.directory>
4
5 <swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir>
6 <swagger.snippetOutput.dir>${project.build.directory}/asciidoc/snippets</swagger.snippetOutput.dir>
7 <generated.asciidoc.directory>${project.build.directory}/asciidoc/generated</generated.asciidoc.directory>
8 <asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
9 <asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory> 10
11 <swagger.input>${swagger.output.dir}/swagger.json</swagger.input>
12
13 </properties>
swagger2markup属性
1 <pluginRepositories>
2 <pluginRepository>
3 <id>jcenter-snapshots</id>
4 <name>jcenter</name>
5 <url>/artifactory/oss-snapshot-local/</url>
6 </pluginRepository>
7 <pluginRepository>
8 <id>jcenter-releases</id>
9 <name>jcenter</name>
10 <url>jcenter.bintray</url>
11 <snapshots>
12 <enabled>false</enabled>
13 </snapshots>
14 </pluginRepository>
15 </pluginRepositories>
16
17 <repositories>
18 <repository>
19 <id>jcentral</id>
20 <name>bintray</name>
21 <url>jcenter.bintray</url>
22 <snapshots>
23 <enabled>false</enabled>
24 </snapshots>
25 </repository>
26 <repository>
27 <id>jcenter-snapshots</id>
28 <name>jcenter</name>
29 <url>/artifactory/oss-snapshot-local/</url>
30 </repository>
31 </repositories>
仓库配置
1 <!-- First, use the swagger2markup plugin to generate asciidoc -->
2 <plugin>
3 <groupId>io.github.swagger2markup</groupId>
4 <artifactId>swagger2markup-maven-plugin</artifactId>
5 <version>${swagger2markup.version}</version>
6 <dependencies>
7 <dependency>
8 <groupId>io.github.swagger2markup</groupId>
9 <artifactId>swagger2markup-import-files-ext</artifactId>
10 <version>${swagger2markup.version}</version>
11 </dependency>
12 <dependency>
13 <groupId>io.github.swagger2markup</groupId>
14 <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
15 <version>${swagger2markup.version}</version>
16 </dependency>
17 </dependencies>
18 <configuration>
19 <swaggerInput>${swagger.input}</swaggerInput>
20 <outputDir>${generated.asciidoc.directory}</outputDir>
21 <config>
22 <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
23 <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
24
25 &tPath>${project.basedir}/src/docs/asciidoc/extensions/overview</tPath>
26 &tPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</tPath>
27 &tPath>${project.basedir}/src/docs/asciidoc/extensions/paths</tPath>
28 &tPath>${project.basedir}src/docs/asciidoc/extensions/security/</tPath>
29
30 &sions.springRestDocs.snippetBaseUri>${swagger.snippetOutput.dir}</sions.springRestDocs.snippetBaseUri>
31 &sions.springRestDocs.defaultSnippets>true</sions.springRestDocs.defaultSnippets>
32 </config>
33 </configuration>
34 <executions>
35 <execution>
36 <phase>test</phase>
37 <goals>
38 <goal>convertSwagger2markup</goal>
39 </goals>
40 </execution>
41 </executions>
42 </plugin>
43
44 <!-- Run the generated asciidoc through Asciidoctor to generate
45 other documentation types, such as PDFs or HTML5 -->
46 <plugin>
47 <groupId>org.asciidoctor</groupId>
48 <artifactId>asciidoctor-maven-plugin</artifactId>
49 <version>1.5.6</version>
50 <!-- Include Asciidoctor PDF for pdf generation -->
51 <dependencies>
52 <dependency>
53 <groupId>org.asciidoctor</groupId>
54 <artifactId>asciidoctorj-pdf</artifactId>
55 <version>1.5.0-alpha.16</version>
56 </dependency>
57 <dependency>
58 <groupId>org.jruby</groupId>
59 <artifactId>jruby-complete</artifactId>
60 <version>1.7.21</version>
61 </dependency>
62 </dependencies>
63 <!-- Configure generic document generation settings -->
64 <configuration>
65 <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
66 <sourceDocumentName>index.adoc</sourceDocumentName>
67 <attributes>
68 <doctype>book</doctype>
69 <toc>left</toc>
70 <toclevels>3</toclevels>
71 <numbered></numbered>
72 <hardbreaks></hardbreaks>
73 <sectlinks></sectlinks>
74 <sectanchors></sectanchors>
75 <generated>${generated.asciidoc.directory}</generated>
76 </attributes>
77 </configuration>
78 <!-- Since each execution can only handle one backend, run
79 separate executions for each desired output type -->
80 <executions>
81 <execution>
82 <id>output-html</id>
83 <phase>test</phase>
84 <goals>
85 <goal>process-asciidoc</goal>
86 </goals>
87 <configuration>
88 <backend>html5</backend>
89 <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
90 </configuration>
91 </execution>
92
93 <execution>
94 <id>output-pdf</id>
95 <phase>test</phase>
96 <goals>
97 <goal>process-asciidoc</goal>
98 </goals>
99 <configuration>
100 <backend>pdf</backend>
101 <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory> 102 </configuration>
103 </execution>
104
105 </executions>
106 </plugin>
插件配置
8.所有配置完成后，控制台输⼊ mvn test 即可完成。
发布评论